<HTML><HEAD><TITLE>write_exdr(+Stream, ?Term)</TITLE>
</HEAD><BODY>[ <A HREF="index.html">Term I/O</A> | <A HREF="../../index.html">Reference Manual</A> | <A HREF="../../fullindex.html">Alphabetic Index</A> ]
<H1>write_exdr(+Stream, ?Term)</H1>
The term Term is written onto the output stream Stream in EXDR-format
(a format for communication with agents in other programming languages).


<DL>
<DT><EM>Stream</EM></DT>
<DD>Integer (stream number) or Atom (symbolic stream name).
</DD>
<DT><EM>Term</EM></DT>
<DD>Prolog term.
</DD>
</DL>
<H2>Description</H2>
    The predicates write_exdr/2 and read_exdr/2 can be used for letting
    ECLiPSe programs exchange data with the host language in an embedded
    environment (e.g.  Java, Tcl).  More generally, they allow exchanging
    data with agents written in programming languages that define a
    mapping from EXDR format to the language's data structures.

<P>
    EXDR defines the abstract data types Integer, Long, Double, String,
    List, Nil, Struct and Anonymous Variable. Their mapping to ECLiPSe
    data types is as follows:

<P>
<PRE>
        EXDR type       ECLiPSe type        e.g.
        ----------------------------------------------
        Integer         integer             123
	Long            integer             10000000000
        Double          float               12.3
        String          string              "abc"
        List            ./2                 [a,b,c]
        Nil             []/0                []
        Struct          compound or atom    foo(bar,3)
        Anon.Variable   var                 _
</PRE>
    The type of the generated EXDR-term is the type resulting from the
    "natural" mapping of the Eclipse terms.  Atoms are written as
    structures of arity 0 (not as strings).
<P>
    Not all ECLiPSe terms have an EXDR representation, e.g. integers longer
    than 64 bits, rationals, suspensions or improper lists.  The predicate
    fails in this case, nevertheless writing a complete but simplified term
    to the stream.  All information about variable sharing and variable
    attributes in the ECLiPSe term is silently lost (no failure).
<P>
    Note that as with all output predicates, the output may be buffered,
    so it may be necessary to flush either by closing the stream or by
    using flush/1.
<P>
    If the output Stream has the compress-flag set, write_exdr/2 will use a
    more compact variant of EXDR encoding, at the expense of encoding speed.
<P>
    More information about EXDR format, including the specification of the
    serialised encoding, can be found in the Embedding and Interfacing Manual.

<H3>Modes and Determinism</H3><UL>
<LI>write_exdr(+, ?) is semidet
</UL>
<H3>Fail Conditions</H3>
Fails if the Term cannot be represented in EXDR format
<H3>Exceptions</H3>
<DL>
<DT><EM>(4) instantiation fault </EM>
<DD>Stream is not instantiated.
<DT><EM>(5) type error </EM>
<DD>Stream is not an atom or an integer.
<DT><EM>(192) illegal stream mode </EM>
<DD>Stream is not an output stream.
<DT><EM>(193) illegal stream specification </EM>
<DD>Stream is an illegal stream specification.
</DL>
<H2>Examples</H2>
<PRE>
Success:
    [eclipse 4]: open(queue(""),update,q),
                 write_exdr(q, foo(12.3,123,["hello",_])),
                 read_exdr(q, Term),
                 close(q).

    Term = foo(12.3, 123, ["hello", _131])
    yes.

Failure:
    write_exdr(q, 617236126172).
    write_exdr(q, 3_4).

Error:
    write_exdr(S, a(b,c)).        (Error 4).
    write_exdr(input, X + 2).     (Error 192).
    write_exdr(atom, X + 2).      (Error 193).



</PRE>
<H2>See Also</H2>
<A HREF="../../kernel/ioterm/read_exdr-2.html">read_exdr / 2</A>, <A HREF="../../kernel/iostream/flush-1.html">flush / 1</A>, <A HREF="../../kernel/iostream/set_stream_property-3.html">set_stream_property / 3</A>, <A HREF="../../kernel/iostream/open-4.html">open / 4</A>
</BODY></HTML>
